16 JSDoc

> Last Format Time：8/11/2026 21:45:41

本笔记由两个 JavaScript 教程目录中的同主题内容合并而成；全部旧知识保留在“旧笔记知识全集（按来源保留）”中，并由导航逐项索引。

当前前端开发关键要点

> [!important] 学习优先级：P2 > - TypeScript 项目仍可用 JSDoc 描述公共 API、复杂约束、弃用信息和示例。 > - 注释重点解释设计意图、边界和原因，不重复代码已经清楚表达的内容。 > - 公共库或跨团队模块应让文档与类型声明、测试和实际行为保持一致。

知识点导航

[现代JS教程与阮一峰ES6 · 0基础简介/JSDoc](./16 JSDoc.md)

基本语法和规范
类型声明
应用到不同的代码结构
配合工具使用

现代前端补充与纠错

> [!info] 修改标记 > - 【修正】：旧教程中错误、过时或容易误导的内容。 > - 【补充】：旧教程未覆盖、但当前前端开发需要掌握的内容。 > - 【修正代码】：替换或校正了旧代码示例。

> [!warning] 下方保留旧语法示例；JSDoc 能提升 JavaScript 工程体验，但不能替代运行时校验。

工程用法

【补充】 对外 API 优先写清参数、返回值、异常、泛型和对象结构；不要为显而易见的局部变量堆注释。
【补充】 可在 // @ts-check 或 jsconfig/tsconfig 的 checkJs 下让 TypeScript 检查 JSDoc 类型，逐步改善纯 JavaScript 项目。
【补充】 外部输入即使有 JSDoc/TypeScript 类型也必须做运行时校验；静态类型会在运行时擦除。
【补充】 类型与实现应保持单一事实来源。若项目已使用 TypeScript，避免维护一套与声明重复且容易漂移的冗长 JSDoc。

【补充代码】

// @ts-check

/**
 * @template T
 * @param {T[]} items
 * @returns {T | undefined}
 */
function first(items) {
  return items[0];
}

@param：用于描述函数参数，格式为 @param {类型} 参数名描述。例如：

/**
 * 计算两个数的和
 * @param {number} num1 第一个加数
 * @param {number} num2 第二个加数
 */
function add(num1, num2) {
    return num1 + num2;
}

@returns 或 @return：用于描述函数返回值，格式为 @returns {类型} 描述 。例如：

/**
 * 计算两个数的和
 * @param {number} num1 第一个加数
 * @param {number} num2 第二个加数
 * @returns {number} 两个数相加的结果
 */
function add(num1, num2) {
    return num1 + num2;
}

@type：用于指定变量或属性的类型，格式为 @type {类型}。例如：

/**
 * @type {string}
 */
const greeting = 'Hello, world!';

@description：用于提供对函数、类、模块等的详细描述，一般写在JSDoc注释开头部分，也可以省略直接在注释第一行书写描述内容。例如：

/**
 * 这是一个Person类，用于创建人的对象实例
 * @description 该类包含姓名和年龄属性，以及一个介绍自己的方法
 */
class Person {
    constructor(name, age) {
        this.name = name;
        this.age = age;
    }
    introduce() {
        return `我叫${this.name}，今年${this.age}岁。`;
    }
}

@example：用于展示使用示例，格式为 @example 示例代码。例如：

/**
 * 计算两个数的乘积
 * @param {number} num1 第一个乘数
 * @param {number} num2 第二个乘数
 * @returns {number} 两个数相乘的结果
 * @example
 * const result = multiply(3, 4);
 * console.log(result); // 输出 12
 */
function multiply(num1, num2) {
    return num1 * num2;
}

类型声明

JSDoc支持多种数据类型的声明，除了基本的 number、string、boolean 等，还包括：

数组：使用 {类型[]} 表示，例如 {number[]} 表示数字数组。

/**
 * 计算数组中所有数字的总和
 * @param {number[]} arr 包含数字的数组
 * @returns {number} 数组元素的总和
 */
function sumArray(arr) {
    return arr.reduce((acc, num) => acc + num, 0);
}

对象：使用 {属性名: 属性类型} 表示，例如 {name: string, age: number} 表示具有 name（字符串类型）和 age（数字类型）属性的对象。

/**
 * 打印用户信息
 * @param {object} user 用户对象
 * @param {string} user.name 用户姓名
 * @param {number} user.age 用户年龄
 */
function printUserInfo(user) {
    console.log(`姓名：${user.name}，年龄：${user.age}`);
}

联合类型：使用 {类型1 | 类型2} 表示，例如 {string | number} 表示可以是字符串或数字。

/**
 * 处理不同类型的值
 * @param {string | number} value 可以是字符串或数字的值
 */
function processValue(value) {
    if (typeof value ==='string') {
        console.log(`这是一个字符串：${value}`);
    } else if (typeof value === 'number') {
        console.log(`这是一个数字：${value}`);
    }
}

应用到不同的代码结构

函数：前面已有示例，在函数定义前添加JSDoc注释来描述函数的功能、参数和返回值等。
类：在类定义前添加JSDoc注释描述类的作用，在类的方法前也可添加注释说明方法的功能、参数和返回值。

/**
 * 这是一个Animal类，用于创建动物对象实例
 */
class Animal {
    constructor(name) {
        this.name = name;
    }
    /**
     * 动物发出叫声
     * @returns {string} 动物的叫声
     */
    makeSound() {
        return `${this.name}发出叫声`;
    }
}

模块：在模块文件顶部添加JSDoc注释，描述模块的功能、导出的内容等。

/**
 * 这是一个工具模块，提供了一些常用的工具函数
 * @module utilityModule
 */
export function formatDate(date) {
    // 具体实现
}
export function validateEmail(email) {
    // 具体实现
}

配合工具使用

生成API文档：可以使用工具如 jsdoc 或 typedoc 来根据JSDoc注释生成API文档。以 jsdoc 为例，先安装 jsdoc：

npm install jsdoc -g

然后在项目根目录运行命令 jsdoc，它会根据项目中的JSDoc注释生成HTML格式的API文档。

代码编辑器提示：许多代码编辑器（如Visual Studio Code）通过安装相关插件（如 vscode-jsdoc），可以根据JSDoc注释提供代码提示和类型检查等功能，帮助开发者更高效地编写代码。

通过遵循上述规范和方法，在项目中正确使用JSDoc进行注释，能够有效提升代码的质量和开发效率。